home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 December: Technology Seed / ATS Dec. '97.toast / Navigation Services SDK 1.0b1 / Interfaces / CIncludes / Navigation.h
Encoding:
C/C++ Source or Header  |  1997-11-20  |  17.0 KB  |  428 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        Navigation.h
  3.  
  4.      Copyright:    © 1984-1997 by Apple Computer, Inc.
  5.                  All rights reserved.
  6.  
  7. */
  8. #ifndef __NAVIGATION__
  9. #define __NAVIGATION__
  10.  
  11. #ifndef __TYPES__
  12. #include <Types.h>
  13. #endif
  14. #ifndef __APPLEEVENTS__
  15. #include <AppleEvents.h>
  16. #endif
  17. #ifndef __TRANSLATION__
  18. #include <Translation.h>
  19. #endif
  20. #ifndef __WINDOWS__
  21. #include <Windows.h>
  22. #endif
  23. #ifndef __CODEFRAGMENTS__
  24. #include <CodeFragments.h>
  25. #endif
  26.  
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30.  
  31. #if PRAGMA_IMPORT_SUPPORTED
  32. #pragma import on
  33. #endif
  34.  
  35. #if PRAGMA_ALIGN_SUPPORTED
  36. #pragma options align=mac68k
  37. #endif
  38.  
  39.  
  40. enum {
  41.     kNavMissingKindStringErr    = -5699,
  42.     kNavInvalidCustomControlMessageErr = -5698,
  43.     kNavCustomControlMessageFailedErr = -5697,
  44.     kNavInvalidSystemConfigErr    = -5696
  45. };
  46.  
  47.  
  48. enum {
  49.     kNavDialogOptionsVersion    = 0,
  50.     kNavReplyRecordVersion        = 0,
  51.     kNavCBRecVersion            = 0,
  52.     kNavFileOrFolderVersion        = 0,
  53.     kNavMenuItemSpecVersion        = 0
  54. };
  55.  
  56. typedef UInt16 NavDataVersion;
  57.  
  58. enum {
  59.                                                                 /* input action codes for NavAskSaveChanges() */
  60.     kNavSaveChangesClosingDocument = 1,
  61.     kNavSaveChangesQuittingApplication = 2,
  62.     kNavSaveChangesOther        = 0
  63. };
  64.  
  65. typedef UInt32 NavAskSaveChangesAction;
  66.  
  67. enum {
  68.                                                                 /* result codes for NavAskSaveChanges() */
  69.     askSaveChangesSave            = 1,
  70.     askSaveChangesCancel        = 2,
  71.     askSaveChangesDontSave        = 3
  72. };
  73.  
  74. typedef UInt32 NavAskSaveChangesResult;
  75.  
  76. enum {
  77.                                                                 /* result codes for NavAskDiscardChanges() */
  78.     askDiscardChanges            = 1,
  79.     askDiscardChangesCancel        = 2
  80. };
  81.  
  82. typedef UInt32 NavAskDiscardChangesResult;
  83.  
  84. enum {
  85.                                                                 /* which elements are being filtered for objects: */
  86.     kNavFilteringBrowserList    = 0,
  87.     kNavFilteringFavorites        = 1,
  88.     kNavFilteringRecents        = 2,
  89.     kNavFilteringShortCutVolumes = 3
  90. };
  91.  
  92. typedef short NavFilterModes;
  93. struct NavFileInfo {
  94.     Boolean                         locked;                        /* file is locked */
  95.     Boolean                         resourceOpen;                /* resource fork is opened */
  96.     Boolean                         dataOpen;                    /* data fork is opened */
  97.     Boolean                         reserved;
  98.     UInt32                             dataSize;                    /* size of the data fork */
  99.     UInt32                             resourceSize;                /* size of the resource fork */
  100.     FInfo                             finderInfo;                    /* more file info: */
  101.     FXInfo                             moreFinderInfo;
  102.     char                             reserved2[212];
  103. };
  104. typedef struct NavFileInfo NavFileInfo;
  105.  
  106. struct NavFolderInfo {
  107.     Boolean                         shareable;
  108.     Boolean                         sharePoint;
  109.     Boolean                         mounted;
  110.     Boolean                         readable;
  111.     Boolean                         writeable;
  112.     Boolean                         reserved;
  113.     UInt32                             numberOfFiles;
  114.     DInfo                             finderInfo;
  115.     DXInfo                             moreFinderInfo;
  116.     char                             reserved2[214];
  117. };
  118. typedef struct NavFolderInfo NavFolderInfo;
  119.  
  120. union FileFolderInfo {
  121.     NavFileInfo                     fileInfo;
  122.     NavFolderInfo                     folderInfo;
  123. };
  124. typedef union FileFolderInfo FileFolderInfo;
  125.  
  126. struct NavFileOrFolderInfo {
  127.     UInt16                             version;
  128.     Boolean                         isFolder;
  129.     Boolean                         visible;
  130.     UInt32                             creationDate;
  131.     UInt32                             modificationDate;
  132.     FileFolderInfo                     fileAndFolder;
  133. };
  134. typedef struct NavFileOrFolderInfo NavFileOrFolderInfo;
  135.  
  136. union eventDataInfo {
  137.     EventRecord *                    event;                        /* for event processing */
  138.     void *                            param;                        /* points to event specific data */
  139. };
  140. typedef union eventDataInfo eventDataInfo;
  141.  
  142. typedef UInt32 NavContext;
  143. struct NavCBRec {
  144.     UInt16                             version;
  145.     NavContext                         context;                    /* used by customization code to call Navigation Services */
  146.     WindowPtr                         window;                        /* the dialog */
  147.     Rect                             customRect;                    /* local coordinate rectangle of customization area */
  148.     Rect                             previewRect;                /* local coordinate rectangle of the preview area */
  149.     eventDataInfo                     eventData;
  150.     char                             reserved[226];
  151. };
  152. typedef struct NavCBRec NavCBRec;
  153.  
  154. typedef NavCBRec *NavCBRecPtr;
  155.  
  156. enum {
  157.     kNavCBEvent                    = 0,                            /* an event has occurred (update, idle events, etc.) */
  158.     kNavCBCustomize                = 1,                            /* protocol for negotiating customization space */
  159.     kNavCBStart                    = 2,                            /* the navigation dialog is starting up */
  160.     kNavCBTerminate                = 3,                            /* the navigation dialog is closing down */
  161.     kNavCBAdjustRect            = 4,                            /* the navigation dialog is being resized */
  162.     kNavCBNewLocation            = 5,                            /* user has chosen a new location in the browser */
  163.     kNavCBShowDesktop            = 6,                            /* user has navigated to the desktop */
  164.     kNavCBSelectEntry            = 7,                            /* user has made a selection in the browser */
  165.     kNavCBPopupMenuSelect        = 8,                            /* signifies that a popup menu selection was made */
  166.     kNavCBAccept                = 9,                            /* user has accepted the navigation dialog */
  167.     kNavCBCancel                = 10,                            /* user has cancelled the navigation dialog */
  168.     kNavCBPreviewToggle            = 11                            /* the preview button was clicked, either its being turned on or off */
  169. };
  170.  
  171. typedef SInt32 NavEventCallbackMessage;
  172. typedef UInt32 NavCallBackUserData;
  173. /* for events and customization: */
  174. typedef pascal void (*NavEventProcPtr)(NavEventCallbackMessage callBackSelector, NavCBRecPtr callBackParms, NavCallBackUserData callBackUD);
  175. /* for preview support: */
  176. typedef pascal Boolean (*NavPreviewProcPtr)(NavCBRecPtr callBackParms, NavCallBackUserData callBackUD);
  177. /* filtering callback information: */
  178. typedef pascal Boolean (*NavObjectFilterProcPtr)(AEDesc *theItem, void *info, NavCallBackUserData callBackUD, NavFilterModes filterMode);
  179.  
  180. #if GENERATINGCFM
  181. typedef UniversalProcPtr NavEventUPP;
  182. typedef UniversalProcPtr NavPreviewUPP;
  183. typedef UniversalProcPtr NavObjectFilterUPP;
  184. #else
  185. typedef NavEventProcPtr NavEventUPP;
  186. typedef NavPreviewProcPtr NavPreviewUPP;
  187. typedef NavObjectFilterProcPtr NavObjectFilterUPP;
  188. #endif
  189.  
  190. enum {
  191.     uppNavEventProcInfo = kPascalStackBased
  192.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(NavEventCallbackMessage)))
  193.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(NavCBRecPtr)))
  194.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(NavCallBackUserData))),
  195.     uppNavPreviewProcInfo = kPascalStackBased
  196.          | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
  197.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(NavCBRecPtr)))
  198.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(NavCallBackUserData))),
  199.     uppNavObjectFilterProcInfo = kPascalStackBased
  200.          | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
  201.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(AEDesc *)))
  202.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(void *)))
  203.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(NavCallBackUserData)))
  204.          | STACK_ROUTINE_PARAMETER(4, SIZE_CODE(sizeof(NavFilterModes)))
  205. };
  206.  
  207. #if GENERATINGCFM
  208. #define NewNavEventProc(userRoutine)        \
  209.         (NavEventUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavEventProcInfo, GetCurrentArchitecture())
  210. #define NewNavPreviewProc(userRoutine)        \
  211.         (NavPreviewUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavPreviewProcInfo, GetCurrentArchitecture())
  212. #define NewNavObjectFilterProc(userRoutine)        \
  213.         (NavObjectFilterUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavObjectFilterProcInfo, GetCurrentArchitecture())
  214. #else
  215. #define NewNavEventProc(userRoutine)        \
  216.         ((NavEventUPP) (userRoutine))
  217. #define NewNavPreviewProc(userRoutine)        \
  218.         ((NavPreviewUPP) (userRoutine))
  219. #define NewNavObjectFilterProc(userRoutine)        \
  220.         ((NavObjectFilterUPP) (userRoutine))
  221. #endif
  222.  
  223. #if GENERATINGCFM
  224. #define CallNavEventProc(userRoutine, callBackSelector, callBackParms, callBackUD)        \
  225.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppNavEventProcInfo, (callBackSelector), (callBackParms), (callBackUD))
  226. #define CallNavPreviewProc(userRoutine, callBackParms, callBackUD)        \
  227.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppNavPreviewProcInfo, (callBackParms), (callBackUD))
  228. #define CallNavObjectFilterProc(userRoutine, theItem, info, callBackUD, filterMode)        \
  229.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppNavObjectFilterProcInfo, (theItem), (info), (callBackUD), (filterMode))
  230. #else
  231. #define CallNavEventProc(userRoutine, callBackSelector, callBackParms, callBackUD)        \
  232.         (*(userRoutine))((callBackSelector), (callBackParms), (callBackUD))
  233. #define CallNavPreviewProc(userRoutine, callBackParms, callBackUD)        \
  234.         (*(userRoutine))((callBackParms), (callBackUD))
  235. #define CallNavObjectFilterProc(userRoutine, theItem, info, callBackUD, filterMode)        \
  236.         (*(userRoutine))((theItem), (info), (callBackUD), (filterMode))
  237. #endif
  238.  
  239. enum {
  240.     kNavCtlShowDesktop            = 0,                            /*    show desktop,                 parms = nil */
  241.     kNavCtlSortBy                = 1,                            /*    sort key field,             parms->NavSortKeyField */
  242.     kNavCtlSortOrder            = 2,                            /*    sort order,                    parms->NavSortOrder */
  243.     kNavCtlScrollHome            = 3,                            /*    scroll list home,            parms = nil */
  244.     kNavCtlScrollEnd            = 4,                            /*    scroll list end,            parms = nil */
  245.     kNavCtlPageUp                = 5,                            /*    page list up,                parms = nil */
  246.     kNavCtlPageDown                = 6,                            /*    page list down,                parms = nil */
  247.     kNavCtlGetLocation            = 7,                            /*    get current location,        parms<-AEDesc */
  248.     kNavCtlSetLocation            = 8,                            /*    set current location,        parms->AEDesc */
  249.     kNavCtlGetSelection            = 9,                            /*    get current selection,        parms<-AEDescList */
  250.     kNavCtlSetSelection            = 10,                            /*    set current selection,        parms->AEDescList */
  251.     kNavCtlShowSelection        = 11,                            /*    make selection visible,        parms = nil */
  252.     kNavCtlOpenSelection        = 12,                            /*    open view of selection,        parms = nil */
  253.     kNavCtlEjectVolume            = 13,                            /*    eject volume,                parms->vRefNum */
  254.     kNavCtlNewFolder            = 14,                            /*    create a new folder,        parms->StringPtr */
  255.     kNavCtlCancel                = 15,                            /*    cancel dialog,                parms = nil */
  256.     kNavCtlAccept                = 16,                            /*    accept dialog default,        parms = nil */
  257.     kNavCtlIsPreviewShowing        = 17,                            /*    query preview status,        parms<-Boolean */
  258.     kNavCtlAddControl            = 18,                            /*  add one control to dialog,    parms->ControlHandle */
  259.     kNavCtlAddControlList        = 19,                            /*    add control list to dialog,    parms->Handle (DITL rsrc) */
  260.     kNavCtlGetFirstControlID    = 20,                            /*    get 1st control ID,            parms<-UInt16 */
  261.     kNavCtlSelectCustomType        = 21,                            /*    select a custom menu item    parms->NavMenuItemSpec */
  262.     kNavCtlSelectAllType        = 22,                            /*  select an "All" menu item    parms->SInt16 */
  263.     kNavCtlGetEditFileName        = 23,                            /*    get save dialog's file name    parms<-StringPtr */
  264.     kNavCtlSetEditFileName        = 24                            /*    set save dialog's file name    parms->StringPtr */
  265. };
  266.  
  267. typedef SInt32 NavCustomControlMessage;
  268.  
  269. enum {
  270.     kAllKnownFiles                = 0,
  271.     kAllReadableFiles            = 1,
  272.     kAllFiles                    = 2
  273. };
  274.  
  275. typedef UInt16 NavPopupMenuItem;
  276.  
  277. enum {
  278.     kNavSortNameField            = 0,
  279.     kNavSortDateField            = 1
  280. };
  281.  
  282. typedef UInt16 NavSortKeyField;
  283.  
  284. enum {
  285.     kNavSortAscending            = 0,
  286.     kNavSortDescending            = 1
  287. };
  288.  
  289. typedef UInt16 NavSortOrder;
  290.  
  291. enum {
  292.     kDefaultNavDlogOptions        = 0x000000E4,                    /* use defaults for all the options */
  293.     kNoTypePopup                = 0x00000001,                    /* don't show file type/extension popup on Open/Save */
  294.     kDontAutoTranslate            = 0x00000002,                    /* don't automatically translate on Open */
  295.     kDontAddTranslateItems        = 0x00000004,                    /* don't add translation choices on Open/Save */
  296.     kExtendPopup                = 0x00000008,                    /* extend translation choices on Open/Save */
  297.     kAllFilesInPopup            = 0x00000010,                    /* "All Files" menu item in the type popup on Open */
  298.     kAllowStationery            = 0x00000020,                    /* allow saving of stationery files */
  299.     kAllowPreviews                = 0x00000040,                    /* allow to show previews */
  300.     kAllowMultipleFiles            = 0x00000080,                    /* allow multiple items to be selected */
  301.     kAllowInvisibleFiles        = 0x00000100,                    /* allow invisible items to be shown */
  302.     kDontResolveAliases            = 0x00000200,                    /* don't resolve aliases */
  303.     kSelectDefaultLocation        = 0x00000400                    /* make the default location the browser selection */
  304. };
  305.  
  306. typedef UInt32 NavDialogOptionFlags;
  307.  
  308. enum {
  309.     kNavTranslateInPlace        = 0,                            /*    translate in place, replacing translation source file (default for Save) */
  310.     kNavTranslateCopy            = 1                                /*    translate to a copy of the source file (default for Open) */
  311. };
  312.  
  313. typedef UInt32 NavTranslationOptions;
  314. struct NavMenuItemSpec {
  315.     UInt16                             version;
  316.     OSType                             menuCreator;
  317.     OSType                             menuType;
  318.     Str255                             menuItemName;
  319.     char                             reserved[245];
  320. };
  321. typedef struct NavMenuItemSpec NavMenuItemSpec;
  322.  
  323. typedef NavMenuItemSpec *NavMenuItemSpecPtr;
  324. typedef NavMenuItemSpecPtr *NavMenuItemSpecHandle;
  325. struct NavTypeList {
  326.     OSType                             componentSignature;
  327.     short                             reserved;
  328.     short                             osTypeCount;
  329.     OSType                             osType[1];
  330. };
  331. typedef struct NavTypeList NavTypeList;
  332.  
  333. typedef NavTypeList *NavTypeListPtr;
  334. typedef NavTypeListPtr *NavTypeListHandle;
  335. struct NavDialogOptions {
  336.     UInt16                             version;
  337.     NavDialogOptionFlags             dialogOptionFlags;            /* option flags for affecting the dialog's behavior */
  338.     Point                             location;                    /* top-left location of the dialog, or {-1,-1} for default position */
  339.     Str255                             clientName;
  340.     Str255                             windowTitle;
  341.     Str255                             actionButtonLabel;            /* label of the default button (or null string for default) */
  342.     Str255                             cancelButtonLabel;            /* label of the cancel button (or null string for default) */
  343.     Str255                             savedFileName;                /* default name for text box in NavPutFile (or null string for default) */
  344.     Str255                             message;                    /* custom message prompt (or null string for default) */
  345.     UInt32                             preferenceKey;                /* a key for to managing preferences for using multiple utility dialogs */
  346.     Handle                             popupExtension;                /* extended popup menu items, an array of NavMenuItemSpecs */
  347.     char                             reserved[494];
  348. };
  349. typedef struct NavDialogOptions NavDialogOptions;
  350.  
  351. /* data returned by the utility dialogs: */
  352. struct NavReplyRecord {
  353.     UInt16                             version;
  354.     Boolean                         validRecord;                /* open/save: true if the user confirmed a selection, false on cancel */
  355.     Boolean                         replacing;                    /* save: true if the user is overwriting an existing object for save */
  356.     Boolean                         isStationery;                /* save: true if the user wants to save an object as stationery */
  357.     Boolean                         translationNeeded;            /* save: translation is 'needed', open: translation 'has taken place' */
  358.     AEDescList                         selection;                    /* open/save: list of AppleEvent descriptors of the chosen object(s) */
  359.     ScriptCode                         keyScript;                    /* open/save: script in which the name of each item in 'selection' is to be displayed */
  360.     FileTranslationSpec **            fileTranslation;            /* open/save: list of file translation specs of the chosen object(s), if translation is needed */
  361.     UInt32                             reserved1;
  362.     char                             reserved[231];
  363. };
  364. typedef struct NavReplyRecord NavReplyRecord;
  365.  
  366. extern pascal OSErr NavLoad(void );
  367.  
  368. extern pascal OSErr NavUnload(void );
  369.  
  370. extern pascal UInt32 NavLibraryVersion(void );
  371.  
  372. extern pascal OSErr NavGetDefaultDialogOptions(NavDialogOptions *dialogOptions);
  373.  
  374. extern pascal OSErr NavGetFile(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavPreviewUPP previewProc, NavObjectFilterUPP filterProc, NavTypeListHandle typeList, NavCallBackUserData callBackUD);
  375.  
  376. extern pascal OSErr NavPutFile(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, OSType fileType, OSType fileCreator, NavCallBackUserData callBackUD);
  377.  
  378. extern pascal OSErr NavAskSaveChanges(NavDialogOptions *dialogOptions, NavAskSaveChangesAction action, NavAskSaveChangesResult *reply, NavEventUPP eventProc, NavCallBackUserData callBackUD);
  379.  
  380. extern pascal OSErr NavCustomAskSaveChanges(NavDialogOptions *dialogOptions, NavAskSaveChangesResult *reply, NavEventUPP eventProc, NavCallBackUserData callBackUD);
  381.  
  382. extern pascal OSErr NavAskDiscardChanges(NavDialogOptions *dialogOptions, NavAskDiscardChangesResult *reply, NavEventUPP eventProc, NavCallBackUserData callBackUD);
  383.  
  384. extern pascal OSErr NavChooseFile(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavPreviewUPP previewProc, NavObjectFilterUPP filterProc, NavTypeListHandle typeList, NavCallBackUserData callBackUD);
  385.  
  386. extern pascal OSErr NavChooseFolder(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavObjectFilterUPP filterProc, NavCallBackUserData callBackUD);
  387.  
  388. extern pascal OSErr NavChooseVolume(AEDesc *defaultSelection, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavObjectFilterUPP filterProc, NavCallBackUserData callBackUD);
  389.  
  390. extern pascal OSErr NavChooseObject(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavObjectFilterUPP filterProc, NavCallBackUserData callBackUD);
  391.  
  392. extern pascal OSErr NavNewFolder(AEDesc *defaultLocation, NavReplyRecord *reply, NavDialogOptions *dialogOptions, NavEventUPP eventProc, NavCallBackUserData callBackUD);
  393.  
  394. extern pascal OSErr NavTranslateFile(NavReplyRecord *reply, NavTranslationOptions howToTranslate);
  395.  
  396. extern pascal OSErr NavCompleteSave(NavReplyRecord *reply, NavTranslationOptions howToTranslate);
  397.  
  398. extern pascal OSErr NavCustomControl(NavContext context, NavCustomControlMessage selector, void *parms);
  399.  
  400. extern pascal OSErr NavDisposeReply(NavReplyRecord *reply);
  401.  
  402. extern pascal Boolean NavServicesCanRun(void );
  403.  
  404. #if GENERATINGCFM
  405. #ifdef __cplusplus
  406. inline pascal Boolean NavServicesAvailable() { return ((NavLibraryVersion != (void*)kUnresolvedCFragSymbolAddress) && NavServicesCanRun()); }
  407. #else
  408. #define NavServicesAvailable()     ((NavLibraryVersion != (void*)kUnresolvedCFragSymbolAddress) && NavServicesCanRun())
  409. #endif
  410. #else
  411. pascal Boolean NavServicesAvailable();
  412. #endif
  413.  
  414. #if PRAGMA_ALIGN_SUPPORTED
  415. #pragma options align=reset
  416. #endif
  417.  
  418. #if PRAGMA_IMPORT_SUPPORTED
  419. #pragma import off
  420. #endif
  421.  
  422. #ifdef __cplusplus
  423. }
  424. #endif
  425.  
  426. #endif /* __NAVIGATION__ */
  427.  
  428.